Atari Mega Archive 1/Atari Mega Archive - Volume 1.iso/program/vbi.arc/VBI.DOC

Text File | 1987-01-01 | 6KB | 116 lines

Documentation for VBI, a vertical blank handler package

Copyright (C) 1987 by Amgem, Inc.

Permission is hereby granted for anyone to make or distribute copies of
this program provided the copyright notice and this permission notice are
retained.

This software, or software containing all or part of it, may not be sold
except with express permission of the authors.

Authors:  Bill Dorsey & John Iarocci

If you have any questions or comments, the authors may be reached at
The Tanj BBS, (301)-251-0675.  Updates and bug fixes may also be obtained
through the above service.


OVERVIEW:

VBI is a vertical blank handler package designed to allow easy access to the
Atari STs vertical blank interrupt system.  It allows programmers to incor-
porate many features which would otherwise require a multi-tasking operating
system into their programs with a minimum of difficulty.  Examples of its
use include alarms, blinking characters, and any other functions that need
to be active all the time without getting in the way of normal program exec-
ution.

The authors have successfuly used this package in a system which tells users
calling in to a BBS that the BBS is down.  It runs in the background, and thus
allows use of editors, compilers, games, etc. while it runs.  When the program
detects a carrier detect, it sends a message to the modem, and toggles the
DTR line, hanging up the modem.

Although this program has been tested and is believed to be bug-free, no
guarantees are made of its functionality or suitability to any application.


USE:

In order to use this package, you will need to compile the file vbi.c using
your C compiler and generate an object file.  This object file will then be
linked with any code you later generate to use the facilities in this package.

Before compiling, you may wish to change some definitions in vbi.h.  If you
are using an RGB system, you will want to change the constant TICKSPERSEC to
the value indicated in vbi.h.  Additionally, you may wish to change other
values, such as QUANTUM, which specifies how often programs are called from
the vertical blank handler.

Be very careful when using BIOS, XBIOS, and GEMDOS functions from within
interrupt routines.  There is a fixed amount of register save space for
calls to these functions, and when they are re-entered several times, crashes
can occur without warning.  Admittedly, there are times when no alternative
exists but to use calls to the operating system.  If crashes occur under
these circumstances, you should first suspect a register space overflow before
blaming your code, or the interrupt handler.

If there is a simple way to tell if the operating system can be called at
a given time, say by checking some system variable, it would be the perfect
solution to the above dilemma.  The interrupt routine could look to see if it
was save to call the operating system before doing so.  If it was safe, it
could go ahead, otherwise, it should wait until it is safe.

On final note.  These interrupt routines must be FAST!  They should pref-
erably complete execution in a few milliseconds.  If they take much longer,
the computer will be slowed down substantially.  The constant QUANTUM can
be increased to relieve this problem somewhat, but the user should be aware
that any routines that take longer than one vertical blank cycle with result
in vertical blank interrupts being masked until their completion.

If you are using a C compiler other than the Mark Williams C compiler, you
may need to make some minor modifications to the code.  The only thing that
requires any explanation is the constant BP which comes from the include
file basepage.h.  It is a pointer to the basepage of the program.  In Alcyon
C, the external variable _base points to the basepage and would thus be used
instead of BP.


FUNCTIONS:

init() - This function initializes the vertical blank handler.  It must be
         called before any vertical blank processes are created.

vbiexit() - This function does a terminate and stay resident call.  It should
            be used only if the vertical blank handler is to be left active
            after program termination.  Failure to use it under these circum-
            stances WILL lead to your computer crashing!

remove() - This function removes the vertical blank handler.  Calling it will
           also disable any existing vertical blank processes.

schedule() - This function is the vertical blank scheduler.  It should not
             be referenced by the user under normal circumstances.

create(a) - This function creates vertical blank processes.  Its single arg-
            ument should be a pointer to the function to be added to the vert-
            ical blank proces queue.  Create will return the process id (an
            integer) of the process it adds to the queue.

delete(a) - This function removes vertical blank processes.  Its single arg-
            ument should be the process id of the process to be deleted.

sleep(a) - This function causes a process not to be called for a fixed amount
           of time.  Its argument is the number of seconds before it is to
           resume execution.  The call will return IMMEDIATELY.  It does not
           take effect until the current process exits.


FILES:

vbi.doc    - you're looking at it
vbi.c      - source code for vbi handler functions
vbi.h      - include file for vbi.c
example.c  - an example program using vbi